/* *****************************************************************************
 * JFab (http://code.google.com/p/jfab)
 * Copyright (c) 2011 JFab.org
 * Admin jfab@jeffreythompson.net
 *
 * See the file "LICENSE.txt" for information on usage and redistribution of
 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
 * *****************************************************************************/

package org.jfab.core.factory;

import java.lang.reflect.Method;
import java.util.List;

import org.jfab.core.collection.CGAnnotationList;
import org.jfab.core.collection.CGParameterList;
import org.jfab.core.collection.CGTypeList;
import org.jfab.core.collection.ModifierList;
import org.jfab.core.collection.ParameterNameList;
import org.jfab.core.model.CGAnnotation;
import org.jfab.core.model.CGType;

/**
 * Defines methods required by a string factory.
 */
public interface StringFactory
{
    /**
     * Clear any cached data.
     */
    void clear();

    /**
     * @param value Value.
     * 
     * @return the given string with the first character converted to upper
     *         case.
     */
    String convertFirstCharacterToLowerCase(String value);

    /**
     * @param value Value.
     * 
     * @return the given string with the first character converted to upper
     *         case.
     */
    String convertFirstCharacterToUpperCase(String value);

    /**
     * @param propertyName Property name.
     * 
     * @return property name converted to a method appropriate string.
     */
    String convertPropertyName(String propertyName);

    /**
     * @param propertyName Property name.
     * 
     * @return property name converted to a member constant appropriate string.
     */
    String convertPropertyNameToStaticName(String propertyName);

    /**
     * @param propertyType Property type.
     * @param propertyName Property name.
     * 
     * @return an accessor method name for the given property.
     */
    String createAccessorNameFor(CGType propertyType, String propertyName);

    /**
     * @param annotations Annotations.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         method declaration.
     */
    String createAnnotationsString(CGAnnotationList annotations);

    /**
     * @param annotation Annotation.
     * 
     * @return a new type string.
     */
    String createAnnotationString(CGAnnotation annotation);

    /**
     * @param args Arguments.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         method call.
     */
    String createArgumentsString(ParameterNameList args);

    /**
     * @param propertyName Property name.
     * 
     * @return a new comment.
     */
    String createCommentFromPropertyName(String propertyName);

    /**
     * @param propertyName Property name.
     * 
     * @return a create method name for the given property.
     */
    String createCreateNameFor(String propertyName);

    /**
     * @param extendsType Extends type.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         class declaration.
     */
    String createExtendsString(CGType extendsType);

    /**
     * @param superClasses Super classes.
     * 
     * @return a string representation of the given parameter, suitable for an
     *         interface declaration.
     */
    String createExtendsString(CGTypeList superClasses);

    /**
     * @param implementsInterfaces Implements interfaces.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         class declaration.
     */
    String createImplementsString(CGTypeList implementsInterfaces);

    /**
     * @param initialValue Initial value.
     * 
     * @return a new initial value string.
     */
    String createInitialValueString(String initialValue);

    /**
     * @param propertyName Property name.
     * 
     * @return a member variable name.
     */
    String createMemberVariableName(String propertyName);

    /**
     * @param modifiers Modifiers.
     * 
     * @return a modifiers string for a field, method, or class.
     * 
     * @see java.lang.reflect.Modifier
     */
    String createModifiersString(ModifierList modifiers);

    /**
     * @param propertyName Property name.
     * 
     * @return a mutator method name for the given property.
     */
    String createMutatorNameFor(String propertyName);

    /**
     * @param parameters Parameters.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         method declaration.
     */
    String createParametersString(CGParameterList parameters);

    /**
     * @param propertyName Property name.
     * 
     * @return a property change name.
     */
    String createPropertyChangeName(String propertyName);

    /**
     * @param memberVariableName Member variable name.
     * 
     * @return a property name.
     */
    String createPropertyName(String memberVariableName);

    /**
     * @param returnType Return type.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         method declaration.
     */
    String createReturnTypeString(CGType returnType);

    /**
     * @param <T> Item type.
     * @param prefix Prefix.
     * @param itemPrefix Item prefix.
     * @param list Items.
     * @param separator Separator.
     * @param helperObject Helper object.
     * @param helperMethod Helper method.
     * 
     * @return a string representation of the given parameter, suitable for an
     *         interface declaration.
     */
    <T> String createStringFromList(String prefix, String itemPrefix,
            List<T> list, String separator, Object helperObject,
            Method helperMethod);

    /**
     * @param throwsTypes Throws types.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         method declaration.
     */
    String createThrowsString(CGTypeList throwsTypes);

    /**
     * @param typeParameters Type parameters.
     * 
     * @return a string representation of the given parameter, suitable for a
     *         compilation unit declaration.
     */
    String createTypeParametersString(List<String> typeParameters);

    /**
     * @return the memberVariablePrefix
     */
    String getMemberVariablePrefix();

    /**
     * @return the typeReferenceSupport
     */
    TypeReferenceSupport getTypeReferenceSupport();

    /**
     * @param memberVariablePrefix the memberVariablePrefix to set
     */
    void setMemberVariablePrefix(String memberVariablePrefix);
}
